Inside Macintosh: AppleScript Scripting Additions Guide /

Chapter 2 - Scripting Addition Commands / Command Definitions

/

Read

The Read command reads data from a file, starting from the file mark and continuing to the end of the file.

Read is one of several commands provided by the Read/Write Commands scripting addition. For more information about using these commands and sample scripts, see "Using Read/Write Commands,".

SYNTAX

read referenceToFile 
      [ from startingByte ]                             ¬
      [ for bytesToRead | to byteToReadTo               ¬
         | until delimiterIncluded | before delimiterExcluded ]  ¬
      [ as className [ using delimiter[s] delimiters ] ]

PARAMETERS

referenceToFile

A reference of the form file nameString or alias nameString, or a file reference number previously obtained with the Open for Access command (see "Notes").
Class: Reference or integer

startingByte

The offset of the byte from which to begin reading. A positive integer indicates the offset from the beginning of the file, and a negative integer indicates the offset from the end of the file.
Class: Integer

bytesToRead

The number of bytes to read. If the from startingByte parameter is included, the Read command reads bytesToRead bytes starting at the specified starting point; otherwise, the Read command begins reading at the file mark. If the value of this parameter is negative, an error occurs.
Class: Integer

byteToReadTo

The offset of the byte to read to. If the from startingByte parameter is included, the Read command reads from the specified starting point to byteToReadTo; otherwise, the Read command begins reading at the file mark. A positive integer indicates the offset from the beginning of the file, and a negative integer indicates the offset from the end of the file.
Class: Integer

delimiterIncluded

A delimiter (such as a tab or return character) to read to. The specified delimiter is included in the read (unless it is an end-of-file delimiter, which is not included). If the from startingByte parameter is included, the Read command reads from the specified starting point to the specified delimiter; otherwise, the Read command begins reading at the file mark.
Class: String

delimiterExcluded

A delimiter (such as a tab or return character) to which to read. The specified delimiter is not included in the read. If the from startingByte parameter is included, the Read command reads from the specified starting point to the specified delimiter; otherwise, the Read command begins reading at the file mark.
Class: String

className

The class of the data to be read. The Read command reads the number of bytes appropriate for a value of the class specified by this parameter. (For details, see "Notes" later in this definition.)
Class: Class

delimiters

If the data being read is text-based, you can use this parameter to specify the delimiters the Read command should use when interpreting the data as values of the class specified by className. (For details, see "Notes" later in this definition.)
Class: String or constant, or a two-item list of strings or constants

RESULT

If the Read command is successful, it returns the data read from the file as text (unless specified otherwise by the as parameter).

EXAMPLES

This example reads MyFile from the 12th byte and to the end of the file.

read file "Hard Disk:MyFile" from 12

The next example reads MyFile from the 12th byte before the end of the file to the end of the file.

read file "Hard Disk:MyFile" from -12

The next example reads 24 bytes of MyFile starting at the 12th byte. If the end of the file is reached before 24 bytes have been read, an error is returned.

read file "Hard Disk:MyFile" from 12 for 24

The next example reads MyFile starting at the end of the file and reading backward until the third byte from the end.

read file "Hard Disk:MyFile" from -1 to -3

If the last characters of file MyFile were "123456", the preceding example would return "654".

NOTES

The file mark is a marker used by the File Manager that indicates the byte at which the Read command expects to begin reading data. By default, the file mark is the first byte of the file. However, running a script like this causes the file mark for MyFile to be moved:

read file "Hard Disk:MyFile" from 1 to 4

The file mark for MyFile is now at byte 5, so the next Read command in the same script begins at byte 5. For example, the command

read file "Hard Disk:MyFile" for 4

reads bytes 5 through 8.

To specify the name (nameString) of a file, use a string of the form "Disk:Folder1:Folder2:...:Filename" as described in Chapter 5, "Objects and References," of the AppleScript Language Guide. If you specify only the name of the file (Filename) instead of its entire pathname, AppleScript attempts to find the file in the current directory.

If you specify a reference to a file or an alias, the Read command attempts to match the reference with a file previously opened with the Open for Access command. If a match is found, it simply reads the specified data. If no match is found, the Read command opens the file, reads the specified data, then closes the file. The file mark for a file opened in this fashion is always at the beginning of the file.

If you specify a file reference number previously obtained with the Open for Access command, the Read command reads the specified data immediately.

You can use the as className parameter to specify how the Read command should interpret the data it reads. If data to be read is not a valid value for the specified value class, the Read command returns an error. The rest of this section describes some of the value classes you can specify and the nature of the data returned if the Read command reads the data successfully.

as list

The Read command returns a list only if the data to be read was written to disk as an AppleScript list. If the data to be read is delimited text, you can specify the delimiters used in the data with the using delimiter parameter, and the Read command creates an AppleScript list based on those delimiters.

For example, this script returns a list of items from MyFile using both tab and return characters in MyFile to separate each item in the list:

           read file "Hard Disk:MyFile" as {text} ¬
              using delimiters {return, tab}

The resulting list, like any other AppleScript list, is comma- delimited. You can't specify more than two delimiters; if you do, Read returns the error -50.

as record

Read returns a record only if the data being read was written to disk as an AppleScript record. Read can't coerce other values
to records.

as integer

If the data consists of a single integer, Read returns the integer. If the data consists of more than one integer, Read returns a list
of integers.

as text

Read returns the data as a string. This is the default behavior if the as className parameter is omitted.

as real

If the data consists of a single real number, Read returns the real number. If the data consists of more than one real number, Read returns a list of real numbers.

as short

The short value is defined by the Read/Write Commands scripting addition as 2 bytes long. This can be is useful if you are reading data from a file that uses short integers rather than the 4-byte integers defined by AppleScript. Read interprets the data as one or more discrete 2-byte values. If the data consists of more than one short value, Read returns a list of shorts. If the data is text, you can specify the delimiters used in the data with the using delimiter parameter, and the Read command attempts to coerce each item between delimiters to a short.

as boolean

If the data consists of a 1-byte Boolean value, Read returns the Boolean value. If the data consists of more than one Boolean value, Read returns a list of Boolean values.

as data

Read returns the data as an uninterpreted stream of hexa-
decimal bytes.

You can also specify other types by enclosing the appropriate four-character code in quotation marks. Here's an example.

read file "Hard Disk:myFile" as "PICT"--returns data as type 'PICT'

ERRORS

Error number	Error message
-38	File <<name>> wasn't open.
-39	End of file error.
-50	Parameter error.
-51	File reference number error.
-108	Out of memory.
-1700	Can't make some data into the expected type.
-1701	Some parameter is missing for <commandName>.
-1704	Some parameter was invalid.
-1705	Operation involving a list item failed.
-1715	Some parameter wasn't understood.
-1718	Reply has not yet arrived.